Description

Verifies if an OAuth 2.0 access token is active and, if it is, returns the token's metadata. This operation implements the token introspection (verification) protocol defined in OAuth 2.0 Token Introspection. This operation is designed for resource servers external to TRIDENT. In these cases, the resource server uses this operation to verify an access token that another application obtained with the obtain a token operation and submitted to it to access resources controlled by it.

Request

POST /trustedx-authserver/oauth/token/verify

Content-Type Header

Content-Type: application/x-www-form-urlencoded; charset=UTF-8

Body

Parameter	Usage	Description
`token`	Required	Token to be verified.

Authorization

The request must contain a bearer access token generated by a TRIDENT authorization server and must be obtained via a client credentials grant type OAuth 2.0 flow. This token must have a scope that includes the urn:safelayer:eidas:oauth:token:introspect value and must be used as explained in RFC 6750. Basically, the token must be included in an Authorization header as follows:

Authorization: Bearer <token>

The response of this operation can contain information on the identity of the user (e.g., a groups attribute that specifies the groups to which this user belongs) that the resource server can use to control the access. For this the scope of the access token must include, in addition to the urn:safelayer:eidas:oauth:token:introspect value, the additional values required for access to the attributes that the application wants to obtain. For instance, a resource server can request an access token whose scope includes the urn:safelayer:eidas:oauth:token:introspect and urn:myorg:group_info values. The identity attributes that a resource server can access are limited by the scope of the access token submitted by the server and not by the scope of the access token that it requests to verify (i.e., the scope of the authorization granted by the user to the application for accessing the resource server).

The following must also be taken into account:

If the authorization is associated to an identity domain (because the authorization token was generated by an authorization server associated to an identity provider), it only allows verifying tokens associated to this identity domain regardless of if the tokens correspond to a user authorization. If an attempt is made to verify a token that does not comply with this criterion, a 403 Forbidden HTTP status code and the UserDomainAccessRequiredException error code is returned in the body of the response.
If the authorization is not associated to an identity domain (because the access token was obtained from an authorization server not associated to an identity provider), any access token can be verified.

Example

POST /trustedx-authserver/oauth/token/verify HTTP/1.1
Host: trustedx.demo.com:443
Authorization: Bearer 5341...7dfa
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
 
token=a5f8...6aaf

Response

Status-Line

If the access token is successfully verified, the HTTP response will contain the following Status-Line (see HTTP Response Status for all the possible cases).

HTTP/1.1 200 OK

Content-Type Header

Content-Type: application/json;charset=UTF-8

Body

JSON object with the verified token's metadata.

{ 
   "active" : {boolean},
   "token_type" : "Bearer",
   "scope" : {string},
   "exp" : {number},
   "iat" : {number},
   "iss" : {string},
   "client_id" : {string},
   "client_claims" : {
      "domain" : {string},
      "sub" : {string},
      "distinguished_name" : {string},
      "name" : {string},
      "acr" : {string},
      "amr" : {array}
   },
   "sub" : {string},
   "user_claims" : {
      "domain" : {string},
      "sub" : {string},
      {attribute1} : {value},
      {attribute2} : {value},
      ...
      "acr" : {string},
      "amr" : {array}
   },
   "times_verified" : {number}
}

Property	Description
`active`	`true` if the token is valid (issued by TRIDENT and not expired); `false` otherwise. When this property is false, it is the only property in the response.
`token_type`	Token type. Always has the `"Bearer"` value.
`scope`	Scope of the verified token.
`exp`	When the token expires, expressed as the number of seconds from 1 January 1970 (UTC).
`iat`	When the token was issued, expressed as the number of seconds from 1 January 1970 (UTC).
`iss`	Token issuer. This fixed value is the base URL of the TRIDENT authorization server plus the `/oauth` suffix.
`client_id`	Identifier of the application registered in TRIDENT for which the verified token was generated.
`client_claims`	Attributes of the application and information on how it was authenticated by TRIDENT. JSON object with the following fields: `sub:` the same value as the first level `client_id` field. `domain:` fixed as `urn:safelayer:eidas:domain:oauth:client`. `distinguished_name:` value of the DN field of the Client application. `name:` value of the Description field of the Client application entity, if present. `acr:` authentication level with which the application was authenticated. Absent for public clients. `amr:` Authentication mechanisms with which the application was authenticated. The format of this property is a JSON array of `strings`. Absent for public clients.
`sub`	User identifier. Absent when an access token is verified that is not associated to any user.
`user_claims`	Claims on the user's identity. Absent when a token is verified that is not associated to any identity domain. JSON object with the following fields: `sub:` The same value as the first level `sub` field. Absent when a token is verified that is not associated to any user. `domain:` Identifier of the user's identity domain. When a token associated to an identity domain but not a user is verified,user_claims only contains this field. `acr:` Authentication level with which the user was authenticated. Absent when a token is verified that is not associated to any user. `amr:` Authentication mechanisms with which the user was authenticated. The format of this property is a JSON array of `strings`. Absent when a token is verified that is not associated to any user. Furthermore, the response can include the following claims, based on the permissions (the values of the scope) of the authorization with which this operation was invoked. These permissions must be specified by the resource server when the authorization token is obtained. These permissions are independent of the scopes of the authorization that the user granted to the application that is requesting access to this server. These claims are always absent when a token not associated to any user is verified. `{attribute1}`, `{attribute2}`, etc.: Identity attributes of the user. They are only included if the authorization includes access permissions to the identity attributes. The permissions can be OpenID Connect scope values `(profile, email`, etc.), customized scope values associated to identity attributes or `urn:safelayer:eidas:full_identity`. See User Information Scopes for more information. `authn_details:` Details on the context and the authorization process of the user. Only included if the authorization includes the `urn:safelayer:eidas:authn_details` permission. See User Information Scopes for more information.
`times_verified`	Number of times that the token had been previously verified, without including the current verification. The first time a token is verified, this field takes the value of 0.

Example: Verification of a User Token

Below is an example of a response message for the verification of a user token. Ellipses have been included to facilitate reading. This example assumes that the scope of the authorization token used has a value that allows obtaining the groups identity attribute of the user (e.g., urn:myorg:group_info), an attribute that the resource server uses for controlling access to its resources. The information returned indicates that the verified token is valid, is associated to a user in the employees identity domain in the Marketing and Sales groups, and that it allows access to the user's email address (the email scope) and a customized scope (urn:myorg:manage_documents).

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Cache-Control: no-store, no-cache, must-revalidate
Pragma: no-cache
 
{
   "active": true,
   "token_type": "Bearer",
   "scope": "email urn:myorg:manage_documents",
   "exp": 1532337898963,
   "iat": 1532334298963,
   "iss": "https://trustedx.demo.com:8082/trustedx-authserver/oauth",
   "client_id": "demoapp",
   "client_claims": {
      "sub": "demoapp",
      "domain": "urn:safelayer:eidas:domain:oauth:client",
      "distinguished_name": "CN=Demo OAuth Client",
      "name": "Demo Application",
      "acr": "urn:safelayer:...:authentication:level:low",
      "amr": [ "urn:oasis:...:am:password" ]
   },
   "sub": "abcd1234fafbfcfd149a9caadca8821",
   "user_claims": {
      "sub" : "abcd1234fafbfcfd149a9caadca8821",
      "domain" : "employees",
      "groups" : [ "Marketing", "Sales" ],
      "acr" : "urn:safelayer:...:authentication:level:medium",
      "amr" : [ "urn:oasis:...:am:password", "urn:oasis:...:am:OTP" ]
   },
   "times_verified": 0
}

Example: Verification of an Administrative Token

Below is an example of a response message for the verification of an access token associated to an identity domain but not a user. Ellipses have been included to facilitate reading. The information returned indicates that the token is valid, is associated to the employees identity domain and allows managing the user accounts (the urn:safelayer:eidas:account:user:manage scope) of this domain.

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Cache-Control: no-store, no-cache, must-revalidate
Pragma: no-cache
 
{
   "active": true,
   "token_type": "Bearer",
   "scope": "urn:safelayer:eidas:account:user:manage",
   "exp": 1532337898963,
   "iat": 1532334298963,
   "iss": "https://trustedx.demo.com:8082/trustedx-authserver/oauth",
   "client_id": "demoapp",
   "client_claims": {
      "sub": "demoapp",
      "domain": "urn:safelayer:eidas:domain:oauth:client",
      "distinguished_name": "CN=Demo OAuth Client",
      "name": "Demo Application",
      "acr": "urn:safelayer:...:authentication:level:low",
      "amr": [ "urn:oasis:...:am:password" ]
   },
   "user_claims": {
      "domain" : "employees"
   },
   "times_verified": 0
}